home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d19 / exzt11.arc / EXZTEST.DOC < prev    next >
Text File  |  1990-06-15  |  17KB  |  524 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                                                                     ExZTEST
  25.  
  26.                                    The On-Line File Integrity Check Program
  27.  
  28.                                           Written for PCBoard v14.5 systems
  29.  
  30.                                                         Release version 1.0
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.                                                 Copyright 1990, Andy Keeves
  47.                                    The Executive Network Information System
  48.                                                         All rights reserved
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.           INTRODUCTION
  75.           ------------
  76.  
  77.                ExZTest is a  simple program  to help file  validation on  a
  78.           PCBoard  v14.5  system.    Starting  with this  version,  PCBoard
  79.           introduced on-line upload  verification and file testing  ability
  80.           through a shelled process. Although it seems simple enough to use
  81.           PKUNZIP's -t option for verification, there are a number of other
  82.           items which can  be done and  were apparently desirable by  some.
  83.           Thus, ExZTest was born.
  84.  
  85.                ExZTest will simply create a PCBFAIL.TXT or PCBPASS.TXT file
  86.           when invoked  with the proper  command line options.  These files
  87.           will be used and displayed by PCBoard to notify the caller of the
  88.           results. 
  89.  
  90.                ExZTest will handle files created  by PKWare's PKZIP, PKPACK
  91.           and PKARC programs, as well as  SEA's ARC and NoGate Consulting's
  92.           PAK programs. Although it relies on the original program (such as
  93.           PKUNZIP)  to  do  the  actual  testing,  it further  studies  the
  94.           compressed file for optional parameters.
  95.  
  96.  
  97.  
  98.           EXZTEST OPERATION AND INSTALLATION
  99.           ----------------------------------
  100.  
  101.                ExZTest  must be  installed in  PCBoard's  PCBTEST.BAT file.
  102.           Note that  PCBoard will  pass two  parameters to  this file,  the
  103.           first being the  path and file  name to test  and the second  the
  104.           optional keyword  UPLOAD. You can do some interesting things with
  105.           this file, of course,  but we'll keep the examples  fairly simple
  106.           here.  Since most Sysops that I know use the .ZIP format for file
  107.           compression we'll concentrate  on that  one. The only  difference
  108.           between .ZIP and the  others is the  program STRIPZIP which I  am
  109.           not aware of existing for the other formats.
  110.  
  111.                I do recommend you run STRIPZIP, not as much for the removal
  112.           of  .ZIP  comments  as  for  the  removal of  any  possible  file
  113.           attributes from the .ZIP just uploaded!   ExZTest assumes you use
  114.           it as a  first step.  If  you wish not  to, you can suppress  the
  115.           related message from ExZTest (keep reading for the switches).
  116.  
  117.                Note that  PKUNZIP, PKUNPAK, PKXARC, PKZIP,  STRIPZIP and/or
  118.           PAK must  be  in  a  DOS search  path  for  ExZTest  to  function
  119.           correctly!  You need  only those programs  which you use on  your
  120.           system, of course.
  121.  
  122.                A  small  program  called CLEARERR.COM  is  included  in the
  123.           distribution as well.  Note that CLEARERR *MUST*  BE LOCATED IN A
  124.  
  125.  
  126.           ExZTEST - On-Line File Integrity Checker for PCBoard 14.5       1
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.           DOS PATH WHEN  EXZTEST IS  RUN!  If curious why  read the  CAVEAT
  140.           section near the end.
  141.  
  142.  
  143.                Here  is  a  sample  PCBTEST.BAT   file  (also  included  in
  144.           ExZTest's distribution):
  145.  
  146.  
  147.           @ECHO OFF
  148.           @EXZTEST %1 0 %2
  149.  
  150.  
  151.                That seems simple enough, doesn't it?  Place ExZTest.COM and
  152.           CLEARERR.COM in a DOS search path and you are nearly ready!
  153.  
  154.                So, why is this better than  simply running PKUNZIP you ask?
  155.           One reason is  that ExZTest  gives you a  simple, clean  response
  156.           file for the caller. You need not display all the notices you get
  157.           from the  other programs.   ExZTest  also performs the  following
  158.           functions for you:
  159.  
  160.                o    Automatically create PCBFAIL.TXT or PCBPASS.TXT;
  161.                o    Generates all  display  files  using  PCBoard's  "@Xnn"
  162.                     color codes;
  163.                o    Tells your  caller what  has been  done, including  the
  164.                     stripping  of the  .ZIP  comment,  verification of  the
  165.                     file, listing of the content;
  166.                o    Optionally removes unwanted files from the .ZIP.
  167.                o    Handles the output properly when PCBoard's TEST command
  168.                     has been invoked;
  169.                o    Optionally, checks the age of the files inside the .ZIP
  170.                     for a Sysop specified  number of days. If the  new file
  171.                     is older, it will be forced to "fail" and upload credit
  172.                     will be withheld pending your review of the file;
  173.                o    Allows the suppression of the Stripzip message;
  174.  
  175.           So, now you begin to see why this is useful, right?  Let's take a
  176.           look at how all this is accomplished through the command line!
  177.  
  178.  
  179.  
  180.           PROGRAM SYNTAX
  181.           --------------
  182.  
  183.                ExZTest  is  invoked through  a  fairly simple  command line
  184.           format,  which  consists of  three  required  fields  and  a  few
  185.           optional switches:
  186.  
  187.                EXZTEST <filename> <days> [UPLOAD] [/switches]
  188.  
  189.           Note that two  of the three fields  required are passed to  it by
  190.           PCBoard via the PCBTEST.BAT file!
  191.  
  192.           ExZTEST - On-Line File Integrity Checker for PCBoard 14.5       2
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.           The following fields are required:
  208.  
  209.                <filename>     This parameter is passed to  us by PCBoard as
  210.                               batch  parameter %1.  It will  likely include
  211.                               the  drive,  path, file  name  and extension.
  212.                               Should an extension be missing, ExZTest  will
  213.                               add a ".ZIP" automatically!
  214.  
  215.                <days>         This is  a required  parameter, expressed  as
  216.                               number of  days backward in time  from today.
  217.                               To disable  date checking,  simply specify  0
  218.                               (zero) for days.   If you wish to allow  only
  219.                               files  of  a  certain age,  however,  you can
  220.                               specify that  here  as number  of  days,  for
  221.                               instance 90 to accept only files dated within
  222.                               the  last 90 days.   Note that  when the .ZIP
  223.                               contains multiple files, the most recent date
  224.                               within the .ZIP file will be used! 
  225.  
  226.                [UPLOAD]       This  parameter  is  also  passed  to  us  by
  227.                               PCBoard  and is also  required. Specify it as
  228.                               batch parameter %2. This  is how ExZTest will
  229.                               know  whether  we  are  executing  a  TEST or
  230.                               checking a new upload.
  231.  
  232.  
  233.           The following switches are all optional:
  234.  
  235.                /NS            This switch will  suppress the automatic  use
  236.                               of Stripzip, which is assumed.  If you do not
  237.                               wish to use Stripzip you must add this to the
  238.                               command line!   Note that StripZip  will ONLY
  239.                               be invoked  if the  file being  tested has  a
  240.                               .ZIP extension!
  241.  
  242.                /W             If a number other than zero was specified for
  243.                               <days> this  switch will tell  ExZTest not to
  244.                               fail the file if it is found to be older than
  245.                               expected,  but rather  to accept it  and warn
  246.                               the caller about  the file's age.   This is a
  247.                               good way to get your callers used to the idea
  248.                               that you'll be  checking the age of  files in
  249.                               the future  and rejecting the  upload, rather
  250.                               than spring it on them overnight.
  251.  
  252.                /@<filespec>   This  is  a  list  file  containing  unwanted
  253.                               names. It is  a simple  ASCII text file,  one
  254.                               name per line, wildcards accepted, specifying
  255.                               file name and extension. If the  file exists,
  256.                               ExZTest will  shell to PKZIP and  instruct it
  257.  
  258.           ExZTEST - On-Line File Integrity Checker for PCBoard 14.5       3
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.                               to  delete  any  of the  files  found  in the
  272.                               listfile from the newly uploaded .ZIP.   This
  273.                               option is  ignored if processing a  file with
  274.                               extension  other  than  .ZIP  of  course.   A
  275.                               typical  use for  this  feature  might be  to
  276.                               remove items from the new upload, such as BBS
  277.                               ads and other undesirable files immediately.
  278.  
  279.                /&<filespec>   If  you wish  to  override ExZTest's  default
  280.                               explanations for  files which  are found  too
  281.                               old (based on your criteria  of days) you can
  282.                               write your own text  file using your favorite
  283.                               editor.  Whatever you place in this file will
  284.                               be taken as is and appended to the PCBFAIL or
  285.                               PCBPASS files, as required.  You can use  any
  286.                               text,  all of PCBoard's  @ variables and @Xnn
  287.                               color  codes, of  course.   If this  optional
  288.                               file specification is  not supplied,  ExZTest
  289.                               will use default explanations.
  290.  
  291.                /b             Turns on the  bell option.   The 'bell'  will
  292.                               sound using different  tones for passing  and
  293.                               failing files (buzz for failure and chime for
  294.                               pass).
  295.  
  296.  
  297.                That  is the  extent of  it. The  command line  is  not case
  298.           sensitive, however, spaces MUST separate the 3 main arguments. 
  299.  
  300.                ExZTest  will  return  one  of  three DOS  errorlevels  upon
  301.           exiting to DOS:
  302.  
  303.                     Error level 0  :    No problems encountered
  304.                     Error level 1  :    Target  file  not found  or command
  305.                                         syntax error identified
  306.                     Error level 2  :    Target file failed tests
  307.  
  308.                I readily admit that I am not sure what you might wish to do
  309.           with this information, however, it is there if desired.
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.           ExZTEST - On-Line File Integrity Checker for PCBoard 14.5       4
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.           CAVEAT
  338.           ------
  339.  
  340.                While working on this  program I discovered what I  can only
  341.           term a  Microsoft bug for  now.  It  apparently is unique  to DOS
  342.           shells performed  from BC7  programs,  possibly other  QuickBasic
  343.           versions as well.   Apparently, during a shell to DOS  from a BC7
  344.           program, the first use of the DOS errorlevel by a program running
  345.           in that shell simply clears the  errorlevel and makes it useable.
  346.           I cannot figure why, but a simple  .BAT file will work every time
  347.           from DOS, correctly setting the errorlevel, while only the second
  348.           setting of the  errorlevel will take if  it is ran from  within a
  349.           BC7 shell.
  350.  
  351.                To resolve this  problem, I included a  small program called
  352.           CLEARERR.COM which clears  the DOS errorlevel  to 0 and makes  it
  353.           reliable withing the  BC7 shell.  As a result,  CLEARERR must  be
  354.           available to ExZTest  while running.   Without it, the reults  of
  355.           all TEST operations and checking of uploads other than .ZIP files
  356.           will be totally  unreliable!  All you  need to do is  place it in
  357.           your DOS  path and  it will restore  the errorlevel to  a useable
  358.           shape. 
  359.  
  360.  
  361.  
  362.           DISCLAIMER
  363.           ----------
  364.  
  365.                EXZTEST  is  distributed  "as  is".   The  author  makes  no
  366.           guarantees as to these programs' ability to run or fitness  for a
  367.           particular purpose in  your specific computing environment.   You
  368.           should  test  this  program  thoroughly  before  using  it  in  a
  369.           production environment.
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.           ExZTEST - On-Line File Integrity Checker for PCBoard 14.5       5
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.           REVISION HISTORY
  404.           ----------------
  405.  
  406.                Version 1.0    June 10, 1990       First release
  407.  
  408.                Version 1.1    June 15, 1990       Maintenance release
  409.  
  410.                  o  Added  checks  for  DOS  version  running under.    The
  411.                     program  will no longer add "@" to the DOS .BAT file if
  412.                     running on DOS versions prior to 3.30
  413.  
  414.                  o  PCBoard's "More?" prompt  is now  suppressed in case  a
  415.                     batch upload with automatic logoff is being tested
  416.  
  417.                  o  File extensions other than .ZIP, .ARC and .PAK will now
  418.                     be treated as .ZIP files.  If they are not they will be
  419.                     failed with an errorlevel of 11 as indicated by PKZIP
  420.  
  421.                  o  The program will  no longer attempt to check file dates
  422.                     if  a  file   has  failed  verification.   Version  1.0
  423.                     attempted  to do  an age  test on  the file if  one was
  424.                     indicated, regardless of previous tests
  425.  
  426.                  o  The "Zip  comment removed"  message will  no longer  be
  427.                     shown if the file has failed verification
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.           ExZTEST - On-Line File Integrity Checker for PCBoard 14.5       6
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.           CREDITS
  470.           -------
  471.  
  472.                ExZTest likely would not have been  created if it wasn't for
  473.           the 'suggestions'  of Mark Rapp  of Microsellar BBS  who actually
  474.           proposed most of  the ideas incorporated in  the program. ExZTest
  475.           was  finally written so  that Mark can  stop asking  about it! :)
  476.           OK,  I admit that I liked the idea  as well, although my use will
  477.           likely be somewhat more limited.
  478.  
  479.                I need to acknowledge the help  I received from Dan Moore in
  480.           some  areas,   specifically  in   the  handling   of  .ZIP   file
  481.           directories.  Although  this program  does  not actually  use his
  482.           code, without it  this program would have taken  a lot longer and
  483.           would have required many more hours of research!
  484.  
  485.                Last but  not least, this  program would be  useless without
  486.           David  Terry's  efforts  (of Clark  Development  Co)  and PCBoard
  487.           14.5's many new features and abilities.
  488.  
  489.                My grateful appreciation to all!
  490.  
  491.  
  492.  
  493.           DISTRIBUTION
  494.           ------------
  495.  
  496.                ExZTest is distributed as Freeware.  As such, no fees of any
  497.           sort may  be charged for  it by anyone.   Any alterations  of the
  498.           code  are  expressly prohibited.   You  may  use ExZTest  free of
  499.           charge  with no limitations.  You may, if you wish, distribute it
  500.           on your BBS,  however, all original files MUST be included in the
  501.           distribution file. All  .ZIP files distributed by  me are stamped
  502.           with PKZIP's authenticity verification stamp, which should NOT be
  503.           removed. Should  you have an  automated process,  such as  ExZip,
  504.           which removes the  stamp, you may download the  authentic version
  505.           anytime from the Executive Network, as a free download.
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.           ExZTEST - On-Line File Integrity Checker for PCBoard 14.5       7
  523.  
  524.